fix: keep event order, measure delays on the monotonic clock, cancel by marking - #665

Three fixes to how the engines order, time and cancel events, and a refactor that removes every suppression from the modules they touch. Each is its own commit, and they can be split into separate PRs if you prefer.

Events due at the same moment kept their order only by chance

Both queues are PriorityQueues ordered by TriggerData.execution_time alone, so triggers with equal times come out in heap order, not the order they were put. A clock coarse enough to stamp two events alike runs them out of order. With every trigger stamped alike, twenty events raised in one callback ran as 0, 2, 6, 14, 19, 18, ..., on both engines and both queues.

TriggerData now numbers each trigger as it is created (itertools.count) and compares that number after execution_time, so triggers due together keep their order.

Delays were measured on the wall clock

Triggers were stamped with time.time() plus their delay and held until time.time() reached the stamp, so a step of the wall clock moved every due time. Stepped back by a time sync, it held even an undelayed event until the clock caught up. Stepped forward, it ran delayed events early. Stamps and the due checks in both engines now use time.monotonic().

Cancelling a delayed event could disorder the others and strand its caller

EventQueue.remove() filtered the list behind the heap, and a filtered heap is not always a heap. Of ten delayed events due from 10 to 90 ms, cancelling the first ran the event due at 50 ms before the one due at 40 ms. The trigger's future was dropped with it, so on the async engine a coroutine awaiting the cancelled event's send() was never answered. Both happen on 3.2.1.

cancel_event() now marks each trigger sent with the send_id as cancelled, in a new TriggerData.cancelled field, and answers its future with None. The triggers stay where they are, so nothing rearranges the heap from outside PriorityQueue, and EventQueue.is_empty() drops cancelled triggers from the head, so the processing loop never checks whether one is due. EventQueue.remove() is renamed cancel().

The suppressions in the touched modules

No type: ignore, noqa, pragma: no cover or pragma: no branch is left in engines/base.py, engines/sync.py, engines/async_.py or statemachine.py. Each was replaced by fixing what it covered:

• BaseEngine declared select_transitions, select_eventless_transitions, _select_transitions, _first_transition_that_matches, microstep and _exit_states as synchronous, and AsyncEngine overrode them with coroutines, which is what the four type: ignore[override] hid. They now belong to SyncEngine, and BaseEngine keeps what both engines share.
• Each processing loop is split into its macrostep, the external events and one external event, and add_descendant_states_to_enter into its history, region and initial-state parts, which takes every function under the complexity limit.
• Removed as unreachable: BaseEngine.empty() and pop(), which nothing called; the _run_microstep() wrappers, since microstep() already sends every error through _handle_error(); the second pass over the internal queue, since the macrostep empties it and spawning invocations puts events only on the external queue; and the checks for an exited state being None.
• SyncEngine.processing_loop() no longer takes a caller_future it never used. Only AsyncEngine.put() attaches a future to an event, so StateChart._processing_loop() now passes one to the async engine alone.
• is_in_final_state() takes the parallel case first, so an atomic state needs no branch of its own.
• StateChart: a cast for the default Model, vars(self).update(), an assert that narrows initial_state (as factory.py does), and _repr_svg_() through the diagram formatter, which renders SVG the same way.

Two lines the pragmas hid now have tests: stop() still stops the engine when cancelling invocations fails, and a transition into a parallel state and a state inside one of its regions enters that state and not the region's initial one.

Tests

• tests/test_event_ordering.py stamps every trigger with one time (by patching statemachine.event_data.monotonic) and checks the order on both engines and both queues, for 0, 1, 2 and 20 events. It failed before its fix.
• tests/test_cancel_event.py runs every test on a clock that moves only when the test moves it.
  • Cancelling the first, a middle or the last of ten delayed events, or the last one queued, leaves the rest in due order.
  • A send_id cancels every event sent with it and nothing else. It is matched exactly: empty, whitespace, line endings, NUL, case, a zero-width space, a byte-order mark, composed against decomposed accents, and ids up to 2048 characters. It never cancels an event sent without one, and a cancel with nothing queued cancels nothing sent later.
  • The loop never reads the clock for a cancelled event, cancel_event() works from inside a callback, and a cancelled trigger is marked rather than removed.
  • A coroutine awaiting a cancelled event gets None, whether it is cancelled once or twice, and a caller that stops waiting, before or while it awaits, leaves its event cancellable.
  • The order test and the awaiting test failed before the fix.
• tests/test_statechart_delayed.py checks that no trigger is stamped or checked on the wall clock (reading time.time fails the test), that the engines read time.monotonic, and that a delay in milliseconds comes due that many thousandths of a second later, for no delay, 0, 1, 50 and -50.
• tests/test_statechart_delayed.py also queues a delayed event from a callback, on a clock that moves 10 ms with every reading, and checks that a coroutine that stops awaiting a delayed event, before or while it awaits, does not stop it firing in due order.
• tests/test_invoke.py::TestEngineStopCleanup and tests/scxml/test_parallel_regions.py cover the two lines the pragmas hid.
• Each test was checked against mutants of the code it covers: 40 in all, every one failed by at least one test without waiting for a timeout.
• The full suite passes with --cov-fail-under=100, along with ruff, mypy and pyright, through the pre-commit hooks.

Release notes are in docs/releases/3.2.2.md.

🤖 Generated with Claude Code